v1.25.12: kubefwd-v1.25.12

Compare Source

What's New

TUI Light/Dark Theme Support (#​393)

The TUI now supports light terminal backgrounds with a new --theme flag and KUBEFWD_THEME environment variable.

# CLI flag
sudo -E kubefwd svc -n default --tui --theme light

# Environment variable
KUBEFWD_THEME=light sudo -E kubefwd svc -n default --tui

The light palette uses darker color variants (dark gold, dark green, dark teal, black text) optimized for readability on light terminal backgrounds. The default remains the dark theme.

Bug Fixes

• Fix MCPB build script for Windows (#​394): Corrected the goreleaser dist directory path for Windows CGO cross-compilation builds.

Changelog

• TUI: add light/dark theme support (#​393)
• fix: use correct goreleaser build ID for Windows MCPB bundles (#​394)

v1.25.10: kubefwd-v1.25.10

Compare Source

v1.25.10

Bug Fixes

• Windows VPN DNS resolution fixed (#​390): Windows users with VPN connections can now connect to clusters when the API server hostname requires VPN-specific DNS resolution. The Go 1.24 upgrade in v1.23.0 broke this because Go's pure-Go DNS resolver doesn't respect Windows per-adapter DNS settings.

Changes

• Windows builds now use CGO (CGO_ENABLED=1) with MinGW cross-compilation to use the native Windows DNS API
• Linux and macOS builds remain static (CGO_ENABLED=0) for Alpine compatibility

Changelog

• 33c0ab8 Add attributions page and CNCF Landscape badge to documentation (#​374)
• 516d002 Add kubefwd documentation files (llms.txt and llms-full.txt) detailing features, installation, usage, and REST API. (#​373)
• f2ad8b7 Bump urllib3 in /.github in the pip group across 1 directory (#​371)
• c08d613 Enable Windows CGO cross-compilation in release workflow (#​391)
• cdf18db Update Installation Documentation for Official Package Managers (#​379)
• f31c27d ci: bump actions/checkout from 6.0.1 to 6.0.2 (#​384)
• fe0291d ci: bump actions/setup-go from 6.1.0 to 6.2.0 (#​376)
• 92e88ef ci: bump actions/setup-python from 6.1.0 to 6.2.0 (#​385)
• 7a8adef ci: bump anchore/sbom-action from 0.21.0 to 0.21.1 (#​377)
• ff3286d ci: bump anchore/sbom-action from 0.21.1 to 0.22.1 (#​383)
• b40fa9d ci: bump docker/login-action from 3.6.0 to 3.7.0 (#​389)
• e5ee353 ci: bump github/codeql-action from 4.31.10 to 4.32.0 (#​382)
• 22b2b83 ci: bump github/codeql-action from 4.31.9 to 4.31.10 (#​378)
• 0fd5f36 ci: bump github/codeql-action from 4.32.0 to 4.32.1 (#​388)
• 7bd7d10 deps: bump github.com/charmbracelet/bubbles from 0.21.0 to 0.21.1 (#​386)
• 15d300e deps: bump github.com/sirupsen/logrus from 1.9.3 to 1.9.4 (#​380)
• 4b472ca deps: bump golang.org/x/sys from 0.39.0 to 0.40.0 (#​375)
• 143c055 docker: bump alpine from 865b95f to 2510918 (#​387)
• fbf95f7 docker: bump ubuntu from c35e29c to cd1dba6 (#​381)

v1.25.9: kubefwd-v1.25.9

Compare Source

MCP Server Improvements

Graceful Startup Without API Connection

The MCP server now starts and registers all tools even when the kubefwd API is unavailable. This enables:

• Registry Discovery: Smithery, Glama.ai, and other MCP registries can now introspect kubefwd's tool definitions without requiring kubefwd to be running
• Better Developer Experience: Tools return helpful, structured error messages guiding users to start kubefwd when the API isn't available

Consistent Error Handling

All MCP tool handlers now return structured ProviderUnavailableError responses with:

• Clear diagnosis explaining the issue
• Suggested actions to resolve
• Retry recommendations

Example error response:

{
  "code": "provider_unavailable",
  "message": "State reader not available",
  "diagnosis": "kubefwd may not be running. Start it with: sudo -E kubefwd",
  "suggested_actions": [{"action": "get_health", "hint": "Check kubefwd status"}],
  "retry_recommended": true
}

New Files

• glama.json: Configuration for Glama.ai MCP registry claiming
• docs/images/kubefwd-logo.svg: Logo asset for documentation

Testing

• Added unit tests for MCP command package (cmd/kubefwd/mcp/mcp_test.go)
• Test coverage for cmd/kubefwd/mcp: 0% → 13.5%
• All existing tests pass
• Lint clean

Upgrade Notes

This is a non-breaking change. The MCP server behavior is improved but maintains backward compatibility. Users who previously ran kubefwd mcp without the API available will now see the server start (with warnings) instead of immediately exiting.

Full Changelog

• Improve MCP server initialization and API connection handling
• Replace generic error messages with structured NewProviderUnavailableError
• Add unit tests for MCP command flags and API connection validation
• Add glama.json configuration file for registry claiming
• Add kubefwd logo SVG for documentation

Changelog

• 7881c5a Fix gofmt -s simplification issues
• 6efedb9 MCP server improvements (#​372)
• dd8a3d2 Quality/gocyclo (#​363)
• cd084ca Quality/housekeeping (#​369)
• 080853c Replace outdated TUI guide with revamped User Guide (#​360)
• bdacb6d Revert "Fix gofmt -s simplification issues"
• 6ad2509 Tests/coverage (#​362)
• b96ea6d ci: bump actions/checkout from 4.2.2 to 6.0.1 (#​370)
• a961053 ci: bump actions/setup-go from 5.2.0 to 6.1.0 (#​368)
• a84426d ci: bump codecov/codecov-action from 5.4.3 to 5.5.2 (#​365)
• 9e9da2d ci: bump github/codeql-action from 3.27.9 to 4.31.9 (#​367)
• f265619 ci: bump golangci/golangci-lint-action from 6.1.1 to 9.2.0 (#​366)
• e8b851f ci: bump ossf/scorecard-action from 2.4.1 to 2.4.3 (#​364)

v1.25.8: kubefwd-v1.25.8

Compare Source

Bug Fixes

• fix: Windows hosts path auto-detection (#​359) - kubefwd now automatically detects the correct hosts file path based on the operating system:

  • Windows: C:\Windows\System32\drivers\etc\hosts
  • Linux/macOS: /etc/hosts

  Previously, the --hosts-path flag defaulted to /etc/hosts on all platforms, causing kubefwd to fail immediately on Windows with "Hosts path does not exist: /etc/hosts".

Changes

• Added runtime import to detect OS at runtime
• Added defaultHostsPath() function that returns OS-appropriate path
• Updated --hosts-path flag to use dynamic default

Windows Support

This release fixes a critical issue that prevented kubefwd from running on Windows without manually specifying the --hosts-path flag. Windows users can now run kubefwd without any additional configuration:

Before (Windows):

kubefwd svc -n mynamespace
FATA[12:34:18] Hosts path does not exist: /etc/hosts

After (Windows):

kubefwd --help | findstr hosts-path
--hosts-path string          Hosts file path. (default "C:\Windows\System32\drivers\etc\hosts")

Installation

Windows

Download from GitHub Releases and extract to your PATH.

# Download and extract (PowerShell)
Invoke-WebRequest -Uri "https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_Windows_x86_64.zip" -OutFile kubefwd.zip
Expand-Archive kubefwd.zip -DestinationPath C:\kubefwd

# Add C:\kubefwd to your PATH

macOS (Homebrew)

brew install txn2/tap/kubefwd

Linux

Download from GitHub Releases or use your package manager.

Verifying This Release

All release artifacts are signed with Sigstore for supply chain security. Each binary archive has its own .sigstore.json signature bundle.

Verify Individual Binaries

# Example: Verify the Linux x86_64 binary
curl -LO https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_Linux_x86_64.tar.gz
curl -LO https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_Linux_x86_64.tar.gz.sigstore.json

cosign verify-blob \
  --bundle kubefwd_Linux_x86_64.tar.gz.sigstore.json \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd/.*" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  kubefwd_Linux_x86_64.tar.gz

Verify Checksums File

curl -LO https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_checksums.txt
curl -LO https://github.com/txn2/kubefwd/releases/download/v1.25.8/kubefwd_checksums.txt.sigstore.json

cosign verify-blob \
  --bundle kubefwd_checksums.txt.sigstore.json \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd/.*" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  kubefwd_checksums.txt

Available Signed Artifacts

Docker Image Verification

cosign verify txn2/kubefwd:v1.25.8 \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd/.*"

v1.25.7: kubefwd-v1.25.7

Compare Source

TUI Browse Modal

Introduces an interactive Browse Modal for discovering and forwarding Kubernetes services directly from the TUI. Press f to open a hierarchical browser that navigates through contexts, namespaces, and services - then forward individual services or entire namespaces without leaving the interface.

Browse Modal Features

• Three-level navigation: Contexts → Namespaces → Services
• Forward services on demand: Select any service and press Enter to start forwarding
• Bulk forwarding: "Forward All" option forwards every service in a namespace
• Visual indicators: Already-forwarded services show a checkmark (✓)
• Port display: See service ports before forwarding
• Context switching: Press c to switch Kubernetes contexts

Keyboard Shortcuts

Use Case

Start kubefwd with minimal namespaces, then dynamically add services as needed:

# Start with one namespace
sudo -E kubefwd svc -n default --tui

# Press 'f' to browse, navigate to another namespace,

# and forward additional services on demand

Bug Fixes

Pod Logs Streamer Reliability

Fixed nil interface issues with clientSet initialization in the TUI pod logs streamer. Improved namespace manager integration ensures reliable log streaming.

Log Spam Prevention

ServiceFWD now tracks "no pods" warnings with a flag to prevent repeated log messages. The flag resets when pods become available, allowing future warnings if pods disappear again.

Test Coverage Improvements

Significant expansion of TUI test coverage:

New test files:

• browse_test.go — 1,277 lines covering BrowseModel navigation, loading states, error handling
• tui_test.go — 1,712 lines covering RootModel, event handling, and UI components

Documentation

Updated API reference and OpenAPI specification with documentation for Kubernetes pod debugging and event endpoints (no new code, documentation only).

CI Updates

• Updated GitHub Actions dependencies for security and compatibility
• Pinned codeql-action/upload-sarif version in Scorecard workflow

No MCP/API Code Changes

This release contains no changes to the MCP server or REST API functionality. All MCP tools (29 total) continue to work as documented in v1.25.6.

Changes

• Add TUI Browse Modal for interactive service discovery (#​358)
• Add API documentation for Kubernetes pod/event endpoints (#​357)
• Code quality improvements (#​353, #​354, #​355)
• Documentation housekeeping (#​356)
• CI dependency updates (#​345, #​346, #​347, #​348, #​349)

Full Changelog

Changelog

• 269f550 Add Kubernetes pod debugging and event APIs (#​357)
• 3f0f812 Documentation and badge housekeepin (#​352)
• f259e34 Housekeeping/documentation (#​356)
• addd289 Potential fixes for 2 code quality findings (#​353)
• fc2215f Potential fixes for 3 code quality findings (#​354)
• 56ad479 Potential fixes for 3 code quality findings (#​355)
• 1351ad1 TUI Browse Modal & Tests (#​358)
• ebe298b ci: bump actions/setup-python from 5.3.0 to 6.1.0 (#​349)
• 76a9fad ci: bump actions/upload-artifact from 4.6.1 to 6.0.0 (#​345)
• 118f9de ci: bump anchore/sbom-action from 0.18.0 to 0.21.0 (#​347)
• a15b5f1 ci: bump docker/setup-buildx-action from 3.7.1 to 3.12.0 (#​348)
• 49b7db3 ci: bump sigstore/cosign-installer from 3.7.0 to 4.0.0 (#​346)

v1.25.6: kubefwd-v1.25.6

Compare Source

Fixes critical issues with the Kubernetes discovery MCP tools introduced in v1.25.5. The tools were defined but their HTTP API routes were not registered, causing 404 errors.

Fixed: Missing API Routes

The following MCP tools now work correctly:

Fixed: Response Format Errors

Fixed: get_connection_info Without Namespace

Previously, calling get_connection_info with only a service name (no namespace) would return 404. Now it:

1. Searches for services matching the name
2. If exactly one match, returns that service's connection info
3. If multiple matches, returns an error listing namespaces to disambiguate

# Now works:
get_connection_info(service_name="postgres")

# If ambiguous, helpful error:
"multiple services found with name 'postgres' in namespaces: [staging, production]. Please specify namespace"

Changes

• Fix missing HTTP routes for 5 MCP Kubernetes discovery tools
• Fix response format for list_pods and get_events
• Fix get_connection_info to work without namespace parameter

Full Changelog

Changelog

• 516bdc3 Fix Missing Kubernetes API Routes for MCP (#​351)
• 60238c7 deps: bump github.com/bep/debounce from 1.2.0 to 1.2.1 (#​344)

v1.25.5: kubefwd-v1.25.5

Compare Source

MCP Kubernetes Discovery Enhancements

Expands MCP server capabilities with comprehensive Kubernetes read operations for debugging and discovery. Previously, users could not inspect Kubernetes resources beyond forwarded services through the MCP interface.

New MCP Tools (5 tools)

Use Cases

Claude Desktop (or any MCP client) can now:

1. Debug a failing service:

   • "What pods are backing auth-service?" → list_pods with service_name filter
   • "Is the pod healthy?" → get_pod for detailed status
   • "Why won't it start?" → get_events for scheduling/pulling/startup events

2. Investigate pod issues:

   • "Show me the logs" → get_pod_logs
   • "What was the last error?" → get_pod_logs with previous=true
   • "Check container status" → get_pod with container details

3. Verify service routing:

   • "Which pods are ready?" → get_endpoints shows ready vs not-ready addresses

Complete MCP Tool Inventory (29 tools)

Forwarding Management (7): add_namespace, remove_namespace, add_service, remove_service, reconnect_service, reconnect_all_errors, sync_service

Service Discovery (7): list_services, get_service, find_services, list_k8s_namespaces, list_k8s_services, list_contexts, get_connection_info, list_hostnames

Pod Operations (5) — NEW: list_pods, get_pod, get_pod_logs, get_events, get_endpoints

Monitoring & Diagnostics (10): get_health, get_quick_status, get_metrics, get_http_traffic, get_analysis, diagnose_errors, get_logs, get_history

OpenSSF Scorecard

Added OpenSSF Scorecard workflow for security best practices monitoring. The scorecard analyzes the repository for security posture including branch protection, dependency management, and code review practices.

Changes

• Add MCP Kubernetes discovery tools for pod/event/endpoint inspection (#​350)
• Add OpenSSF Scorecard security analysis workflow (#​343)

Full Changelog

v1.25.4: kubefwd-v1.25.4

Compare Source

This release focuses on MCP tool response, code quality improvements, test reliability, and bug fixes identified by GitHub's security scorecard and code quality analysis tools.

Bug Fixes

MCP Tool Response Format

• Fixed all 24 MCP tool handlers to return complete JSON data instead of text summaries
• AI clients now receive full structured data when using MCP tools like list_services, add_namespace, etc.
• Resolves issue where add_namespace reported "Discovered 0 services" despite successful forwarding

SLSA Provenance Generation

• Fixed artifact hash generation in release workflow
• Previous implementation failed silently when certain file types (e.g., .zip) didn't exist
• Now uses find command to reliably locate all artifacts before hashing

Test Improvements

Eliminated Flaky Tests

• Replaced time.Sleep patterns with proper synchronization using waitForCondition helper
• Affected tests in pkg/fwdsvcregistry now poll for conditions instead of arbitrary delays

Race Condition Fixes

• Replaced sync.Once with mutex-protected bool in pkg/fwdapi/manager.go and pkg/fwdapi/logbuffer.go
• Tests can now properly reset and restore global state without race conditions

Code Quality

• Replaced confusing string(rune('0'+i)) patterns with fmt.Sprintf for clarity
• Fixed invalid port number (99999 → 65535) in network error test
• Replaced custom contains helper with strings.Contains
• Improved non-string conversion test to verify actual type assertions

Build/CI Improvements

• Pinned GoReleaser version to ~> v2.13 in both CI and release workflows
• Improved artifact hash generation reliability for SLSA provenance

Full Changelog

Changed Files

• .github/workflows/ci.yml - Pin GoReleaser version
• .github/workflows/release.yml - Pin GoReleaser version, fix hash generation
• pkg/fwdapi/logbuffer.go - Replace sync.Once with mutex pattern
• pkg/fwdapi/logbuffer_test.go - Improve test reliability and clarity
• pkg/fwdapi/manager.go - Replace sync.Once with mutex pattern
• pkg/fwdapi/manager_test.go - Update for new initialization pattern
• pkg/fwdmcp/httpclient_test.go - Fix invalid port number
• pkg/fwdmcp/tools.go - Return nil CallToolResult for proper JSON responses
• pkg/fwdmcp/tools_test.go - Update tests for new handler behavior
• pkg/fwdmetrics/httpsniff_test.go - Replace confusing string expressions
• pkg/fwdns/manager_test.go - Use strings.Contains
• pkg/fwdsvcregistry/fwdsvcregistry_test.go - Add waitForCondition, eliminate time.Sleep

Changelog

• 0271289 MCP Registry Readiness (#​341)
• 1f7def5 MCP and Test Quality Improvements (#​342)

v1.25.3: kubefwd-v1.25.3

Compare Source

Changelog

• 41931d2 Improve Unit Test Coverage (#​340)

v1.25.2: kubefwd-v1.25.2

Compare Source

This release focuses on security improvements, OpenSSF Scorecard compliance, and MCP bug fixes.

Highlights

Security Fix: IP Parsing Bounds Validation

Fixed CodeQL security alert for incorrect integer conversion in IP parsing. The ipFromString() function now validates that each octet is within 0-255 bounds before casting to byte, preventing potential overflow issues.

MCP Bug Fixes

• Fixed namespace state corruption - remove_namespace no longer corrupts state for subsequent add_service calls
• Fixed service discovery reporting - add_namespace now correctly reports discovered service count via direct K8s API query
• Restored parameter hints - All MCP tool descriptions now include required parameter hints (e.g., "Requires key (e.g., 'servicename.namespace.context')")

OpenSSF Scorecard Improvements

• Pinned all workflow dependencies by SHA hash
• Restricted token permissions to job-level scope
• Expected Scorecard improvement: Pinned-Dependencies 8→10/10, Token-Permissions 0→10/10

MCPB Bundle Signing

MCPB bundles are now signed with Cosign and included in SLSA provenance attestation for enhanced supply chain security.

What's New

Security

• Fixed CodeQL alert: bounds validation for IP octet parsing (#​339)
• Added fuzz tests for IP parsing to catch edge cases (#​336)
• Fixed panic in ipFromString for malformed input (#​336)

Bug Fixes

• Fixed remove_namespace corrupting state for subsequent add_service calls (#​338)
• Fixed add_namespace reporting "Discovered 0 services" (#​338)
• Restored MCP tool parameter hints that were accidentally removed (#​338)
• Added missing switch cases for StatusPending and StatusStopping (#​338)
• Fixed nil pointer panic in fwdsvcregistry.GetAll() (#​338)

Build/CI

• Improved OpenSSF Scorecard compliance (#​337)
• Pinned workflow dependencies by SHA hash
• Restricted token permissions to job-level
• Sign MCPB bundles with Cosign (#​335)
• Include MCPB bundles in SLSA provenance attestation
• Fix MCPB build script for goreleaser arm64 directory naming (#​334)
• Pin mkdocs-material version in docs workflow
• Add fuzz testing to CI workflow

Testing

• Added fuzz tests for IP parsing functions
• Added 11 unit tests for IP octet bounds validation
• Added tests covering values >255, negative values, edge cases

Dependencies

• Bumped github.com/quic-go/quic-go from 0.54.0 to 0.57.0

Installation

Homebrew (macOS/Linux)

brew install txn2/tap/kubefwd

Claude Desktop (MCPB)

Download the appropriate .mcpb file for your platform and double-click to install.

Binary Download

Download the appropriate archive for your platform from the release assets.

Docker

docker pull txn2/kubefwd:v1.25.2

Package Managers

• APK: kubefwd_amd64.apk, kubefwd_arm64.apk
• DEB: kubefwd_amd64.deb, kubefwd_arm64.deb
• RPM: kubefwd_amd64.rpm, kubefwd_arm64.rpm

Checksums & Verification

All release artifacts include:

• SHA256 checksums in kubefwd_checksums.txt
• Sigstore signature in kubefwd_checksums.txt.sigstore.json
• SBOM (Software Bill of Materials) for each archive
• SLSA Level 3 provenance attestation

Verify signatures with:

cosign verify-blob \
  --bundle kubefwd_checksums.txt.sigstore.json \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd/.github/workflows/release.yml@refs/tags/.*" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  kubefwd_checksums.txt

Breaking Changes

None.

Upgrade Notes

This is a drop-in replacement for v1.25.1. No configuration changes required.

Contributors

Thanks to all contributors who made this release possible.

Full Changelog

See the commit log for the complete list of changes.

Changelog

• b4ffd89 Add fuzz testing to CI workflow
• 6345ab0 Add fuzz tests and fix panic in ipFromString
• a7735fa Fix CodeQL autobuild and improve Scorecard compliance
• c762a68 Fix CodeQL security alert (#​339)
• 8bbb961 Fix MCPB build script for goreleaser arm64 directory naming
• bdd56dd Improve OpenSSF Scorecard - Pin dependencies and restrict token permissions (#​337)
• 64510b0 MCP Bug Fixes and Improvements (#​338)
• ce94be8 Pin mkdocs-material version in docs workflow
• cafed0b Sign MCPB bundles with Cosign and include in SLSA provenance
• 56615cf deps: bump github.com/quic-go/quic-go from 0.54.0 to 0.57.0

v1.25.1: kubefwd-v1.25.1

Compare Source

This release focuses on MCP (Model Context Protocol) stability improvements, MCPB bundle distribution for Claude Desktop, and enhanced test coverage.

Highlights

MCPB Bundle Support for Claude Desktop

kubefwd now ships with .mcpb bundles for one-click installation in Claude Desktop:

• macOS (Intel): kubefwd-1.25.1-darwin-amd64.mcpb
• macOS (Apple Silicon): kubefwd-1.25.1-darwin-arm64.mcpb
• Windows: kubefwd-1.25.1-windows-amd64.mcpb

Simply download and double-click to install kubefwd as an MCP server in Claude Desktop.

MCP Stability Improvements

• Fixed add_service race condition - The tool now waits for pod discovery to complete before returning, ensuring services appear in state immediately with correct connection info
• Improved tool descriptions - All 23 MCP tools now explicitly document required parameters, helping AI assistants use them correctly on the first try
• Enhanced namespace removal - Added proper cleanup of orphaned forwards and services when namespaces are removed

Event Bus Enhancements

• Added NamespaceRemoved event type for proper cleanup coordination
• Implemented unsubscribe logic for event handlers to prevent memory leaks
• Added blocking/unblocking logic to prevent race conditions during namespace removal

What's New

Features

• MCPB bundle generation and distribution via GitHub releases
• NamespaceRemoved event type and handler for TUI cleanup
• RemoveByNamespace method to clean up orphaned forwards and services
• MCP mode detection with banner suppression for cleaner output
• PodAdded event subscription for accurate service initialization

Bug Fixes

• Fixed race condition in add_service MCP tool that returned before pod discovery completed
• Fixed namespace removal leaving orphaned services in state store
• Fixed potential race conditions during namespace removal operations

Documentation

• Expanded MCP integration guide with detailed capability descriptions
• Added API documentation image to reference guide
• Updated README with new links for API Reference and MCP Integration
• Fixed typo: "API Refrence" → "API Reference"

Testing

• Added comprehensive MCP integration tests (398+ lines)
• Added test utilities and fixtures for MCP state management
• Added tests for RemoveByNamespace functionality
• Added tests for namespace blocking/unblocking behavior
• Added event bus unsubscribe tests
• Added TUI event handling tests

Dependencies

• Bumped golang.org/x/crypto from 0.44.0 to 0.45.0

Installation

Homebrew (macOS/Linux)

brew install txn2/tap/kubefwd

Claude Desktop (MCPB)

Download the appropriate .mcpb file for your platform and double-click to install.

Binary Download

Download the appropriate archive for your platform from the release assets.

Docker

docker pull txn2/kubefwd:v1.25.1

Package Managers

• APK: kubefwd_amd64.apk, kubefwd_arm64.apk
• DEB: kubefwd_amd64.deb, kubefwd_arm64.deb
• RPM: kubefwd_amd64.rpm, kubefwd_arm64.rpm

Checksums & Verification

All release artifacts include:

• SHA256 checksums in kubefwd_checksums.txt
• Sigstore signature in kubefwd_checksums.txt.sigstore.json
• SBOM (Software Bill of Materials) for each archive
• SLSA Level 3 provenance attestation

Verify signatures with:

cosign verify-blob \
  --bundle kubefwd_checksums.txt.sigstore.json \
  --certificate-identity-regexp="https://github.com/txn2/kubefwd" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
  kubefwd_checksums.txt

Breaking Changes

None.

Upgrade Notes

This is a drop-in replacement for v1.25.0. No configuration changes required.

Contributors

Thanks to all contributors who made this release possible.

Full Changelog

See the commit log for the complete list of changes.

Changelog

• 2514351 Add API documentation image to reference guide
• 6bd4863 Add MCP mode detection and banner suppression logic
• 6d7d1d0 Add NamespaceRemoved event type and its handler
• 833ee0b Add RemoveByNamespace to clean up orphaned forwards and services
• f52eeaf Add script and workflows to build and upload MCPB bundles
• 6af4115 Add test utilities and integration tests for MCP state management
• 6078193 Add tests for RemoveByNamespace in store
• 8a0b841 Add tests for namespace blocking and unblocking behavior in state store
• 684f61a Add unsubscribe logic and tests for event handlers in Bus implementation
• 8b5b215 Emit NamespaceRemoved event after service removal
• 77fc7dc Fix typo in README: correct "API Refrence" to "API Reference"
• b6439a0 Handle NamespaceRemoved event in TUI
• e95fad3 Improve context handling and logging for namespace and service operations
• 0c07d77 Prevent race conditions during namespace removal by introducing blocking/unblocking logic in the state store
• 5111771 Revise and expand MCP integration guide with enhanced feature descriptions
• 971c307 Specify required parameters in MCP tool descriptions
• 6695eb4 Subscribe to PodAdded events for services to ensure accurate initialization
• 4aca09f Update README with new links for API Reference and MCP Integration
• da3255f deps: bump golang.org/x/crypto from 0.44.0 to 0.45.0

v1.25.0: kubefwd-v1.25.0

Compare Source

This is a major release introducing a REST API for programmatic control and an MCP (Model Context Protocol) server for AI assistant integration. Developers can now manage port forwards dynamically through API calls or by chatting with AI tools like Claude Desktop, Cursor, and VS Code Copilot. This release also introduces "idle mode" for daemon-style operation, allowing kubefwd to start without any namespaces and add them on-the-fly.

Highlights

• REST API: Full-featured HTTP API with 40+ endpoints for programmatic control, real-time SSE event streaming, and OpenAPI documentation
• MCP Server: First-class integration with AI assistants via 23 tools, 8 resources, and 10 prompts
• Idle Mode: Run kubefwd without namespaces, add/remove them dynamically via API or MCP
• AI-Optimized Analysis: Endpoints designed for LLM consumption with structured errors and suggested actions
• Security Hardening: CORS origin whitelist and bounded memory allocations

New Features

REST API (PR #​330)

kubefwd now includes a comprehensive REST API built with Gin, enabling programmatic control over port forwarding:

# Start kubefwd with API enabled
sudo -E kubefwd svc -n default --api

# Or use idle mode (API enabled by default)
sudo -E kubefwd

# Test the API
curl http://kubefwd.internal/api/health

API Features

• 40+ Endpoints: Complete control over services, forwards, namespaces, and diagnostics
• OpenAPI Documentation: Interactive docs at http://kubefwd.internal/docs
• SSE Event Streaming: Real-time events at /api/v1/events
• AI-Optimized Endpoints: /api/v1/analyze and /api/v1/status designed for LLM consumption
• History Tracking: Event, error, and reconnection history with ring buffer storage

Key Endpoints

Example: Add a Namespace Dynamically

# Add a namespace to forward
curl -X POST http://kubefwd.internal/api/v1/namespaces \
  -H "Content-Type: application/json" \
  -d '{"namespace": "staging", "context": "my-cluster"}'

# List forwarded services
curl http://kubefwd.internal/api/v1/services

# Remove when done
curl -X DELETE http://kubefwd.internal/api/v1/namespaces/staging.my-cluster

MCP Server Integration (PR #​330)

kubefwd now includes a full Model Context Protocol server for seamless AI assistant integration:

# Start MCP server on stdio (for Claude Desktop, Cursor, etc.)
kubefwd mcp

# MCP over HTTP (connects to running kubefwd API)
kubefwd mcp --http

MCP Capabilities

• 23 Tools: Complete control from AI conversations
• 8 Resources: Expose state to AI assistants
• 10 Prompts: Guided workflows for common tasks

Available Tools

Available Resources

Available Prompts

Claude Desktop Integration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "kubefwd": {
      "command": "kubefwd",
      "args": ["mcp"],
      "env": {
        "KUBECONFIG": "/Users/you/.kube/config"
      }
    }
  }
}

Then chat naturally with Claude:

"Connect me to the postgres database in the staging namespace"
"What services are currently having errors?"
"Show me connection info for the auth-service"

Cursor Integration

Add to Cursor settings:

{
  "mcp": {
    "servers": {
      "kubefwd": {
        "command": "sudo",
        "args": ["-E", "kubefwd", "mcp"],
        "type": "stdio"
      }
    }
  }
}

Idle Mode (PR #​330)

kubefwd can now run without specifying namespaces upfront, enabling daemon-style operation:

# Start in idle mode (no namespaces, API enabled by default)
sudo -E kubefwd

# Add namespaces via API
curl -X POST http://kubefwd.internal/api/v1/namespaces \
  -d '{"namespace": "production"}'

# Or via MCP (from AI assistant)

# "Forward the production namespace"

This is particularly useful for:

• Long-running development environments: Start once, add namespaces as needed
• CI/CD pipelines: Programmatically control which services are forwarded
• AI-driven workflows: Let AI assistants manage port forwarding based on context

Namespace Manager (PR #​330)

New dynamic namespace management system (pkg/fwdns):

• Add namespaces at runtime: No restart required
• Remove namespaces cleanly: Stops all forwards, cleans up hosts file
• Label selectors: Filter services within a namespace
• Multi-context support: Forward from multiple clusters simultaneously

Security Improvements

CORS Origin Whitelist

The API now uses an explicit origin whitelist instead of Access-Control-Allow-Origin: *:

var allowedOrigins = map[string]bool{
    "http://kubefwd.internal":   true,
    "http://localhost":          true,
    "http://localhost:8080":     true,
    "http://127.0.0.1":          true,
    "http://127.0.0.1:8080":     true,
    "http://127.2.27.1":         true,
    "http://127.2.27.1:8080":    true,
}

Bounded Memory Allocations (CWE-770)

All ring buffer allocations now have explicit bounds to prevent memory exhaustion:

• Event history: max 10,000 entries
• Error history: max 5,000 entries
• Reconnection history: max 2,000 entries per service
• Log buffer: max 10,000 entries

Improvements

AI-Friendly Error Handling

Errors now include machine-readable codes and suggested actions:

{
  "error": {
    "code": "CONNECTION_REFUSED",
    "message": "Failed to connect to pod",
    "suggestion": "The pod may not be ready. Try 'reconnect_service' after the pod is running.",
    "affectedService": "postgres.default.minikube"
  }
}

Event History

New ring buffer-based history system tracks:

• Service lifecycle events (added, removed, connected, errored)
• Errors with timestamps and context
• Reconnection attempts with success/failure status

HTTP Traffic Inspection

Monitor HTTP requests flowing through port forwards:

# Via API
curl http://kubefwd.internal/api/v1/services/myapi.default.ctx/http

# Returns recent requests with method, path, status, duration

OpenAPI Documentation

Interactive API documentation available at /docs:

• Try endpoints directly from the browser
• Full request/response schemas
• Auth